/*
 * To change this template, choose Tools | Templates
 * and open the template in the editor.
 */

package ca.uwindsor.cs.deepweb.estimation.experiment.common;

import java.util.List;

import ca.uwindsor.cs.deepweb.model.Corpus;

/**
 *
 * @author Liang Jie
 */
public interface EstimatorClientInterface {

    /**
     * Add a term to query. A term used here follows the query parser syntax <a href="http://lucene.apache.org/java/docs/queryparsersyntax.html">query parser syntax</a>
     * @param term a term send to query
     */
    void addTerm(String term);

    /**
     * Get all supported Chinese corpora
     * @return the list of Corpus object
     */
    List<Corpus> getChineseCorpora();

    /**
     * Get all supported corpora
     * @return the list of Corpus object
     */
    List<Corpus> getCorpora();

    /**
     * Get the document IDs with their frequency in CSV includes the following columns sperated by tab:<br/>
     * "ID", "frequency" </br>
     * Warning: use setOutputDocumentFrequency(true) before invoke this method, default is false.
     * @see #setOutputDocumentFrequency(boolean)
     * @return document IDs with their frequency in CSV
     */
    String getDocFrequncy();

    /**
     * Get the document IDs with their size in CSV includes the following columns sperated by tab:<br/>
     * "ID", "size" </br>
     * Warning: use setOutputDocumentSize(true) before invoke this method, default is false.
     * @return document IDs with their size in CSV
     */
    String getDocSize();

    /**
     * Get the Document Frequency CSV includes the following columns sperated by tab:<br/>
     * "occurrence", "quatity"
     * @deprecated Naming error, should be getDocumentFrequencyDistribution()
     * @return the document frequency distribution
     */
    String getDocumentFrequency();

    /**
     * Get the Document Frequency CSV includes the following columns:<br/>
     * "occurrence", "quatity"
     * @return the document frequency in CSV
     */
    String getDocumentFrequencyCSV();

    /**
     * Get the Document Frequency CSV includes the following columns sperated by tab:<br/>
     * "occurrence", "quatity" </br>
     * Warning: use setOutputDocumentFrequencyDistribution(true) before invoke this method, default is true.
     * @return the document frequency distribution
     */
    String getDocumentFrequencyDistribution();

    /**
     * Retrun the result of document id, its number of unique terms and number of total terms
     * @return the document id, its number of unique terms and number of total terms
     */
    String getDocumentNumberofUniqueandTotalTerms();

    /**
     * Get all supported English corpora
     * @return the list of Corpus object
     */
    List<Corpus> getEnglishCorpora();

    /**
     * Get the result CSV that has the following columns:<br/>
     * "Query word", "Accumulative Unique", "Accumulative Total", "OR", "Percentage", "Estimated Size",
     * "Query Return", "Duplicated from Last Query Result", "Marked"
     * @return the estimate result in CSV
     */
    String getEstimateResultCSV();

    /**
     * Get the result that has the following columns sperated by tab:<br/>
     * "Query word", "Accumulative Unique", "Accumulative Total", "OR", "Percentage", "Estimated Size",
     * "Query Return", "Duplicated from Last Query Result", "Marked"
     * @return the estimate result
     */
    String getEstimationResult();

    /**
     * Get the Size Distribution CSV include the following columns sperated by tab:<br/>
     * "Interval", "Quality"<br/>
     * Warning: use setOutputDocumentSizeDistribution(true) before invoke this method, default is true.
     * @return the size distribution in CSV
     */
    String getSizeDistribution();

    /**
     * Get the Size Distribution CSV include the following columns:<br/>
     * "Interval", "Quality"
     * @return the size distribution in CSV
     */
    String getSizeDistributionCSV();

    /**
     * To get if document frequency is set to output
     * Warning: The service may take more time to return results
     * @return ture or false
     */
    boolean isOutputDocumentFrequency();

    /**
     * To get if document size is set to output
     * @return ture or false
     */
    boolean isOutputDocumentSize();

    /**
     * To get if the number of document's unique terms is need in the output
     * Warning: The service may take more time to return results
     * @return ture or false
     */
    boolean isOutputDocumentUniqueTerms();

    /**
     * Run query. Only after the Corpus has been set and terms have been added.
     * After execution, the query result, document frequency, size distribution have been set to the correspoding lists. Use their getters to retrieve the content
     * @return the result xml
     * @see #getSizeDistributionCVS(), #getDocumentFrequencyCVS(), #getEstimateResultCVS()
     */
    String run();

    /**
     * Issuse a sample query that take 10 words with step size 1000 to query. This could be used to test if the connection is ok.
     * @return the sample result xml file
     */
    String runSampleQuery();

    /**
     * Set the corpus that query against
     * @param corpustoquery
     */
    void setCorpustoquery(Corpus corpustoquery);

    /**
     * To set if document frequency is need in the output, default is false.
     * Warning: The service may take more time to return results
     * @param isOutputDocumentFrequency ture or false
     */
    void setOutputDocumentFrequency(boolean isOutputDocumentFrequency);

    /**
     * To set if document frequency distribution is need in the output, default is true.
     * Warning: The service may take more time to return results
     * @param isOutputDocumentFrequencyDistribution flag
     */
    void setOutputDocumentFrequencyDistribution(boolean isOutputDocumentFrequencyDistribution);

    /**
     * To set if document size is need in the output, default is false.
     * Warning: The service may take more time to return results
     * @param isOutputDocumentSize ture or false
     */
    void setOutputDocumentSize(boolean isOutputDocumentSize);

    /**
     * To set if document size distribution is need in the output, default is true.
     * Warning: The service may take more time to return results
     * @param isOutputDocumentSizeDistribution flag
     */
    void setOutputDocumentSizeDistribution(boolean isOutputDocumentSizeDistribution);

    /**
     * To set if the number of document's unique terms is need in the output, default is false.
     * Warning: The service may take more time to return results
     * @param isOutputDocumentUniqueTerms flag
     */
    void setOutputDocumentUniqueTerms(boolean isOutputDocumentUniqueTerms);

    /**
     * Set the step size of a query
     * @param stepsize the step size
     */
    void setStepSize(int stepsize);

}
